Copyright

Connect ODBC for Informix Dynamic Server

© 2001 MERANT. All rights reserved.

DataDirect, INTERSOLV, Middleware, and SequeLink, are registered trademarks, and Client/Server MiddleWare, DataDirect Connect ADO, DataDirect Connect Integrator, DataDirect Connect JDBC, DataDirect Connect ODBC, DataDirect Connect OLE DB, DataDirect Connect Premium, DataDirect Reflector, DataDirect SequeLink Integrator, MERANT, and WebDBLink are trademarks of MERANT. All other trademarks are the property of their respective owners.


About Connect ODBC for Informix Dynamic Server
About the Informix Dynamic Server Driver

Connect ODBC for Informix Dynamic Server (the "Informix Dynamic Server driver") supports multiple connections to the Informix database system version 9.x in the Windows and UNIX environments.

The Informix Dynamic Server driver file name is IVIFCLnn.DLL, where nn is the revision level.


System Requirements
Driver Requirements

There are no database client requirements for the Informix Dynamic Server driver.


Configuring Data Sources

To configure an Informix Dynamic Server data source:

1	Start the ODBC Administrator to display a list of data sources.

2	If you are configuring an existing data source, select the data source name and click Configure to display the ODBC Informix Dynamic Server Driver Setup dialog box.

If you are configuring a new data source, click Add to display a list of installed drivers. Select Informix and click Finish to display the ODBC Informix Dynamic Server Driver Setup dialog box.

3	On the General tab, provide the following information; then, click Apply.

Data Source Name: Type a string that identifies this Informix data source configuration in the system information. Examples include "Accounting" or "INFORMIX-Serv1."

Description: Type an optional long description of a data source name. For example, "My Accounting Database" or "Informix 7 files on Server number 1."

Host Name: Type the name of the machine on which the Informix server resides.

Port Number: Type the port number of the server listener.

Server Name: Type the name of the Informix server as it appears in the sqlhosts file.

Database Name: Type the name of the database to which you want to connect by default.

User Name: Type your user name as specified on the Informix server.

4	Click Test Connect to attempt to connect to the data source using the connection properties specified in the Driver Setup dialog box.

5	On the Advanced tab, provide any of the following optional information; then, click Apply.

Cancel Detect Interval: Select a value other than "0 - None" to allow long-running queries in threaded applications to be canceled if the application issues a SQLCancel. The value you select determines how often (in seconds) the driver checks whether a query has been canceled using SQLCancel. If the driver determines that SQLCancel has been issued, the query is canceled. For example, if you select 5, then for every pending query, the driver checks every five seconds to see whether the application has canceled execution of the query using SQLCancel. The default is 0, which means that queries are not canceled even if SQLCancel is issued.

Application Using Threads: Select this check box to ensure that the driver works with multi-threaded applications. You can clear this check box when using the driver with single-threaded applications. Clearing this check box avoids the additional processing required for ODBC thread-safety standards.

Trim Blank From Index Name: Select this check box to specify whether the leading space should be trimmed from a system-generated index name. This option is provided to address problems with applications that cannot process a leading space in index names. When this box is checked (the default), the driver trims the leading space.

Translate: Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the system information. DataDirect provides a translator named "OEM to ANSI" that translates your data from the IBM PC character set to the ANSI character set.

Select a translator; then, click OK to close this dialog box and perform the translation.

6	Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.


Test Connection

At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection properties specified in the Driver Setup dialog box. A Logon dialog box is displayed. After providing connection information, click OK.

•	If the driver can connect, it releases the connection and displays a "connection established" message. Click OK.

•	If the driver cannot connect because of an improper environment or incorrect connection value, it will display an appropriate error message.

Verify that the all required client software is properly installed. If it is not, you will see the message:

Specified driver could not be loaded due to system error [xxx].

Click OK.


Connecting to Data Source Using a Logon Dialog
Connecting to a Data Source Using a Logon Dialog Box

Some ODBC applications display a Logon dialog box when you are connecting to a data source. In these cases, the data source name has already been specified.

In the Logon dialog box, do the following:

1	Type the name of the host machine on which the Informix server resides.

2	Type the port number of the server listener.

3	Type the name of the Informix server as it appears in the sqlhosts file.

4	Type the name of the database to which you want to connect.

5	If required, type your user name as specified on the Informix server.

6	If required, type your password.

7	Click OK to complete the logon and to update these values in the system information.


Connecting to Data Source Using a Connection String
Connecting to a Data Source Using a Connection String

If your application requires a connection string to connect to a data source, you must specify the data source name that tells the driver which section of the system information to use for the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the system information. These values are not written to system information.

You can specify either long or short names in the connection string. The connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...]

An example of a connection string for Informix is

DSN=Informix TABLES;DB=PAYROLL

The paragraphs that follow give the long and short names for each attribute, as well as a description. The defaults listed are initial defaults that apply when no value is specified in either the connection string or in the data source definition in the system information. If you specified a value for the attribute when configuring the data source, that value is the default.

ApplicationUsingThreads (AUT): ApplicationUsingThreads={0 | 1}. Ensures that the driver works with multi-threaded applications. The default is 1, which makes the driver thread-safe. When using the driver with single-threaded applications, you may set this option to 0 to avoid additional processing required for ODBC thread safety standards.

CancelDetectInterval (CDI): A value in seconds that determines how often the driver checks whether a query has been canceled using SQLCancel. If the driver determines that SQLCancel has been issued, the query is canceled. This attribute determines whether long-running queries in threaded applications are canceled if the application issues a SQLCancel. If set to 0 (the initial default), queries are not canceled even if SQLCancel is issued.

For example, if CancelDetectInterval is set to 5, then for every pending request, the driver checks every five seconds to see whether the application has canceled execution of the query using SQLCancel.

Database (DB): Name of the database to which you want to connect.

DataSourceName (DSN): Identifies an Informix data source configuration in the system information. Examples include "Accounting" or "Informix-Serv1."

HostName (HOST): Name of the machine on which the Informix server resides.

LogonID (UID): Your user name as specified on the Informix server.

PortNumber (PORT): The port number of the server listener. There is no default value.

ServerName (SRVR): The name of the server running the Informix database.

TrimBlankFromIndexName (TBFIN): TrimBlankFromIndexName={0 | 1}. Specifies whether or not the leading space should be trimmed from a system-generated index name. This option is provided to address problems with applications that cannot process a leading space in index names.  When set to 1 (the default), the driver trims the leading space. When set to 0, the driver does not trim the space.


Data Types

The Informix data types map to the standard ODBC data types as follows:

Informix	ODBC
Blob	SQL_LONGVARBINARY
Boolean	SQL_BIT
Byte	SQL_LONGVARBINARY
Char	SQL_CHAR
Clob	SQL_LONGVARCHAR
Date	SQL_TYPE_DATE
Datetime year to fraction(5)	SQL_TYPE_TIMESTAMP
Datetime year to second	SQL_TYPE_TIMESTAMP
Datetime year to day	SQL_TYPE_DATE
Datetime hour to second	SQL_TYPE_TIME
Datetime hour to fraction(5)	SQL_TYPE_TIME
Decimal	SQL_DECIMAL
Float	SQL_DOUBLE
Int8	SQL_BIGINT
Integer	SQL_INTEGER
Interval year(p) to year	SQL_INTERVAL_YEAR
Interval year(p) to month	SQL_INTERVAL_YEAR_TO_MONTH
Interval month(p) to month	SQL_INTERVAL_MONTH
Interval day(p) to day	SQL_INTERVAL_DAY
Interval day(p) to hour	SQL_INTERVAL_DAY_TO_HOUR
Interval day(p) to minute	SQL_INTERVAL_DAY_TO_MINUTE
Interval day(p) to second	SQL_INTERVAL_DAY_TO_SECOND
Interval day(p) to fraction(f)*	SQL_INTERVAL_DAY_TO_SECOND
Interval hour(p) to hour	SQL_INTERVAL_HOUR
Interval hour(p) to minute	SQL_INTERVAL_HOUR_TO_MINUTE
Interval hour(p) to second	SQL_INTERVAL_HOUR_TO_SECOND
Interval hour(p) to fraction(f)*	SQL_INTERVAL_HOUR_TO_SECOND
Interval minute(p) to minute	SQL_INTERVAL_MINUTE
Interval minute(p) to second	SQL_INTERVAL_MINUTE_TO_SECOND
Interval minute(p) to fraction(f)*	SQL_INTERVAL_MINUTE_TO_SECOND
Interval second(p) to second	SQL_INTERVAL_SECOND
Interval second(p) to fraction(f)*	SQL_INTERVAL_SECOND
Interval fraction to fraction(f)*	SQL_VARCHAR
Lvarchar	SQL_VARCHAR
Money	SQL_DECIMAL
Nchar	SQL_CHAR
Serial	SQL_INTEGER
Serial8	SQL_BIGINT
Smallfloat	SQL_REAL
Smallint	SQL_SMALLINT
Text	SQL_LONGVARCHAR
* Fraction(f) types are mapped to fraction(5) in the driver. The precision is type dependent and the scale is 5.


Isolation and Lock Levels Supported

The Informix Dynamic Server driver supports the following isolation levels:

•	0 (read uncommitted)

•	1 (read committed

•	3 (serializable)

Informix supports record-level locking.


ODBC Conformance Level

The API functions supported are listed in Supported ODBC Functions, found in the General Help section of Connect ODBC Help. In addition, the following functions are supported:

•	SQLColumnPrivileges

•	SQLForeignKeys

•	SQLTablePrivileges

The driver supports the minimum SQL grammar.


Number of Connections and Statements Supported

The Informix Dynamic Server driver supports multiple connections and multiple statements per connection to the Informix database system.


General Tab, ODBC Informix Driver Setup
General Tab, ODBC Informix Dynamic Server Driver Setup

Use the ODBC Informix Dynamic Server Driver Setup dialog box to create new Informix data sources or configure existing data sources.

Data Source Name: Type a string that identifies this Informix data source configuration in the system information. Examples include "Accounting" or "Informix-Serv1."

Description: Type an optional long description of a data source name. For example, "My Accounting Database" or "Informix files on Server number 1."

Host Name: Type the name of the machine on which the Informix server resides.

Port Number: Type the port number of the server listener.

Server Name: Type the name of the Informix server as it appears in the sqlhosts file.

Database Name: Type the name of the database to which you want to connect by default.

Advanced Tab

Displays the Advanced tab, where you can configure optional data source settings, such as cancel detect interval.

OK

Cancel

Apply

Test Connect


Advanced Tab, ODBC Informix Driver Setup
Advanced Tab, ODBC Informix Dynamic Server Driver Setup

Use the Advanced tab on the ODBC Informix Dynamic Server Driver Setup dialog box to specify optional settings when you create new Informix data sources or configure existing data sources.

Cancel Detect Interval: Select a value other than "0 - None" to allow long-running queries in threaded applications to be canceled if the application issues a SQLCancel. The value you select determines how often (in seconds) the driver checks whether a query has been canceled using SQLCancel. If the driver determines that SQLCancel has been issued, the query is canceled. For example, if you select 5, then for every pending query, the driver checks every five seconds to see whether the application has canceled execution of the query using SQLCancel. The default is 0, which means that queries are not canceled even if a SQLCancel is issued.

Application Using Threads: Select this check box to ensure that the driver works with multi-threaded applications. You can clear this check box when using the driver with single-threaded applications. Clearing this check box avoids the additional processing required for ODBC thread-safety standards.

Trim Blank From Index Name: Select this check box to specify whether the leading space should be trimmed from a system-generated index name. This option is provided to address problems with applications that cannot process a leading space in index names. When this box is checked (the default), the driver trims the leading space.

Translate Button

Displays the Select Translator dialog box, where you can select a translator to translate your data from one character set to another. Choose the OEM to ANSI translator to translate your data from the IBM PC character set to the ANSI character set.

OK

Cancel

Apply

Test Connect


Logon to Informix Dialog
Logon to Informix Dynamic Server Dialog Box

Host Name: Type the name of the host machine on which the Informix server resides.

Port Number: Type the port number of the server listener.

Server Name: Type the name of the Informix server as it appears in the sqlhosts file.

Database Name: Type the name of the database to which you want to connect.

User Name: Type the name of the user as specified on the Informix server.

Password: Type the user's password.


Apply Button

Writes the settings you have specified to the system information. These settings remain in effect until you change them in this dialog box. Clicking Cancel does not affect settings that have been applied.


OK Button

Writes the settings you have specified to the system information and closes the dialog box.


Cancel Button

Closes the dialog box without saving settings that have not been applied.


Contacting Technical Support

MERANT provides technical support for all registered users of this product, including limited installation support for the first 30 days. If you need support after that time, contact us using one of the methods below or purchase further support by enrolling in the SupportNet program. For more information about SupportNet, contact your sales representative.

The MERANT Web site contains up-to-date technical support information under SupportNet. SupportNet Online is our global service network that provides access to valuable tools and information in an online community for users. Our SupportNet Community shares information via the Web, automatic email notification, newsgroups, and regional user groups. SupportNet Online also includes a KnowledgeBase that allows you to search on keywords for technical bulletins and how-to information. You can also download fix releases for your DataDirect products.

World Wide Web

http://support.merant.com

E-Mail

USA, Canada, and Mexico	datadirect.answerline@merant.com
Australia and New Zealand	australia.answerline@merant.com
Japan	jpn.answerline@merant.co.jp
All other countries	int.datadirect.answerline@merant.com
Local Telephone Support

Local phone numbers can be found at http://support.merant.com/websupport/contact/supportnetanswerline.asp.

Live Answerline telephone support is available 24 hours a day, seven days a week.

Fax and Mail Information

Fax US	1 919 461 4527
Fax Int.	+32 (0) 15-320919
Mail	1500 Perimeter Park Drive, Suite 100, Morrisville, NC 27560 USA

Information to Provide

When you contact us, please include this information:

•	The product serial number located on the Product Registration Information card or on a product serial number card in the box. The number will be checked to verify your eligibility to receive support. If you do not have a current SupportNet contract, we will ask that you speak with a sales representative.

•	Your name and organization. On a first-time call, you may be asked for full customer information including location and contact details.

•	The version number of the DataDirect product you are using.

•	The type and version of the operating system you are using.

•	Any third party software and other environmental information necessary to understand the problem.

•	A brief description of the problem and the steps necessary to re-create it. Specific error messages are needed. Depending on the complexity of the problem, you may be asked to submit a recreatable example demonstrating the problem.

•	An assessment of the severity level of the reported problem.


DTC Support
MTS Support

The Informix Dynamic Server driver can take advantage of Microsoft Transaction Server (MTS) capabilities, specifically, the Distributed Transaction Coordinator (DTC) using the XA Protocol. For a general discussion of MTS and DTC, refer to the help file of the "Microsoft Transaction Server SDK."


Persisting a Result Set as an XML Data File

This driver allows you to persist a result set as an XML data file with embedded schema. To implement XML persistence, a client application must do the following:

1	Turn on STATIC cursors. For example:

SQLSetStmtAttr (hstmt, SQL_ATTR_CURSOR_TYPE, SQL_CURSOR_STATIC, SQL_IS_INTEGER)

2	Execute a SQL statement. For example:

SQLExecDirect (hstmt, "Select * from GTABLE", SQL_NTS)

3	Persist the result set as an XML data file. For example:

SQLSetStmtAttr (hstmt, SQL_PERSIST_AS_XML, "c:\temp\GTABLE.XML", SQL_NTS)

Note regarding Step 1: A result set can be persisted as an XML data file only if the result set is generated using STATIC cursors. Otherwise, the following error is returned:

Driver only supports XML persistence when using driver's static cursors.

Note regarding Step 3: A new statement attribute is available to support XML persistence, SQL_PERSIST_AS_XML. A client application must call SQLSetStmtAttr with this new attribute as an argument. See the following table for the definition of valid arguments for SQLSetStmtAttr.

Argument	Definition
StatementHandle	The handle of the statement that contains the result set to persist as XML.
Attribute	SQL_PERSIST_AS_XML. This new statement attribute can be found in the file qesqlext.h, which is installed with the driver.
ValuePtr	Pointer to a URL that specifies the full path name of the XML data file to be generated. The directory specified in the path name must exist, and if the specified file name exists, the file will be overwritten.
StringLength	The length of the string pointed to by ValuePtr or SQL_NTS if ValuePtr points to a null terminated string.

A client application can choose to persist the data at any time that the statement is in an executed or cursor positioned state. At any other time, the driver will return the following message:

Function Sequence Error


Windows
Windows Support

The following Windows operating systems are supported:

•	Windows 95

•	Windows 98

•	Windows NT with Service Pack 4 and higher

•	Windows 2000

•	Windows Me